feat(cloudwatch-appsignals-mcp-server): Add get_enablement_guide MCP tool #1585

yiyuan-he · 2025-10-24T22:58:19Z

Fixes

Summary

Adding new get_enablement_guide MCP tool. The goal of this tool is to fetch the appropriate enablement guide for AI Assistants to correctly follow Application Signals enablement steps. Currently, these AI-friendly enablement guides will be hosted in this MCP repo. Long-term, we aim to replace our public documentation entirely with these new enablement guides.

Changes

Added get_enablement_guide tool in enablement_tools.py
Created enablement_guides/templates/ directory structure for markdown guides
Added placeholder EC2 + Python enablement guide for testing purposes
Avoided registering this tool since it is not yet ready for release
Added unit tests covering validation, error cases, and successful guide fetching

User experience

Before:
Users had to manually feed relevant pieces of the enablement docs in small chunks to AI Assistants because the public documentation is not AI-friendly. Feeding the entire documentation to the AI assistant led to poor and inconsistent enablement results.

After:
With a single query like:

Enable Application Signals for my Python Flask Application running on EC2. My infrastructure code is in <iac_directory> and my app code is in <app_directory>.

The AI assistant will now automatically retrieve the relevant enablement guide based on the context and follow the enablement instructions. The end result is customers will have AI-generated changes to their IaC code that they can deploy and start seeing Application Signals telemetry.

Checklist

If your change doesn't seem to apply, please leave them unchecked.

I have reviewed the contributing guidelines
I have performed a self-review of this change
Changes have been tested
Changes are documented

Is this a breaking change? (N)

RFC issue number:

Checklist:

Migration process documented
Implement warnings (if it can live side by side)

Acknowledgment

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of the project license.

Copilot

Pull Request Overview

This PR adds a new get_enablement_guide MCP tool to help AI assistants automatically retrieve and follow Application Signals enablement instructions. The tool accepts platform, language, and directory paths as inputs, validates them, and returns an AI-friendly enablement guide with context-specific instructions.

Key Changes:

Introduces the get_enablement_guide function with parameter validation and path resolution
Creates directory structure for storing platform/language-specific enablement guides
Implements comprehensive test coverage for validation, error handling, and successful guide retrieval

Reviewed Changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
`awslabs/cloudwatch_appsignals_mcp_server/enablement_tools.py`	Core implementation of the `get_enablement_guide` function with validation logic and template loading
`tests/test_enablement_tools.py`	Unit tests covering invalid inputs, missing directories, and successful guide fetching
`enablement_guides/templates/ec2/ec2-python-enablement.md`	Placeholder markdown file for EC2+Python enablement guide

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

...loudwatch-appsignals-mcp-server/awslabs/cloudwatch_appsignals_mcp_server/enablement_tools.py

codecov · 2025-10-24T22:59:20Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 90.20%. Comparing base (8d4587c) to head (5c53987).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1585      +/-   ##
==========================================
+ Coverage   90.08%   90.20%   +0.11%     
==========================================
  Files         751      597     -154     
  Lines       54377    46128    -8249     
  Branches     8672     7402    -1270     
==========================================
- Hits        48988    41611    -7377     
+ Misses       3454     2897     -557     
+ Partials     1935     1620     -315

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

thpierce

Did not review tests yet.

...loudwatch-appsignals-mcp-server/awslabs/cloudwatch_appsignals_mcp_server/enablement_tools.py

…r ai agent

…ablement guides

...loudwatch-appsignals-mcp-server/awslabs/cloudwatch_appsignals_mcp_server/enablement_tools.py

…scription

…iption

wangzlei

Can we put all enablement md files in src/cloudwatch-appsignals-mcp-server/awslabs/cloudwatch_appsignals_mcp_server/enablement_guides/templates/ ?

yiyuan-he · 2025-11-05T22:07:10Z

Can we put all enablement md files in src/cloudwatch-appsignals-mcp-server/awslabs/cloudwatch_appsignals_mcp_server/enablement_guides/templates/ ?

Will do this in a quick follow-up PR.

yiyuan-he · 2025-11-06T20:14:30Z

Removed hold-merging and awaiting-codeowners labels as two codeowners have reviewed/approved this PR.

…tool (awslabs#1585) * add get_enablement_guide tool without registering it * apply ruff check . --fix * fix pre-commit checks * additional unit test coverage * require absolute paths for new get_enablement_guide tool * update docstring to specify md format * update with fallback for unsupported language and/or platform * update tool description to instruct agent to create a work/todo list * update tool description with platform and language detection hints for ai agent * add fallback instructions for agent in case it is not able to read enablement guides * remove exists() checks * loosen edit restrictions to also include dependency files * consolidate enablement change guidelines into tool description * refactor to make language and platform tool parameters enums * rename enablement tool to get_application_signals_enablement_guide * standardize error_msg construction for logging * remove redundant debug logs for iac_path and app_path * update agent to surface platform/language not supported message to user * move template file debug statement * run pre-commit checks * add use this tool when guidance to enablement tool description * apply suggested changes * replace temp_directories fixture with module-level constant * rename platform to service_platform for consistency * shorten enablement tool name back to get_enablement_guide * revert enums back to strings to surface friendly error message * add additional tets for code coverage * add guidance for AI agents to resolve paths before calling tool in description * add explicit checklist workflow instructions in enablement tool description * remove generic verify step from tool instructions

add get_enablement_guide tool without registering it

e964e4d

Copilot AI review requested due to automatic review settings October 24, 2025 22:58

yiyuan-he requested review from a team, iismd17, mxiamxia and syed-ahsan-ishtiaque as code owners October 24, 2025 22:58

github-project-automation bot added this to awslabs/mcp Project Oct 24, 2025

github-project-automation bot moved this to To triage in awslabs/mcp Project Oct 24, 2025

Copilot AI reviewed Oct 24, 2025

View reviewed changes

...loudwatch-appsignals-mcp-server/awslabs/cloudwatch_appsignals_mcp_server/enablement_tools.py Outdated Show resolved Hide resolved

yiyuan-he added 3 commits October 24, 2025 16:06

apply ruff check . --fix

48fac03

fix pre-commit checks

b4281cd

additional unit test coverage

4e63eb4

yiyuan-he force-pushed the get-enablement-guide-tool-setup branch from bd78c95 to 4e63eb4 Compare October 27, 2025 16:01

yiyuan-he and others added 4 commits October 27, 2025 09:08

Merge branch 'main' into get-enablement-guide-tool-setup

6c5b3cb

Merge branch 'main' into get-enablement-guide-tool-setup

bd393b1

require absolute paths for new get_enablement_guide tool

73a3cfb

Merge branch 'main' into get-enablement-guide-tool-setup

f0c36ea

scottschreckengaust added waiting-for-codeowners Code owners are needed to review hold-merging Signals to hold the PR from merging labels Oct 28, 2025

thpierce reviewed Oct 28, 2025

View reviewed changes

yiyuan-he and others added 8 commits October 29, 2025 08:35

Merge branch 'main' into get-enablement-guide-tool-setup

dd03ab3

update docstring to specify md format

ce817df

update with fallback for unsupported language and/or platform

644acda

update tool description to instruct agent to create a work/todo list

bf98d59

update tool description with platform and language detection hints fo…

97a4026

…r ai agent

add fallback instructions for agent in case it is not able to read en…

909bb7c

…ablement guides

remove exists() checks

19de394

loosen edit restrictions to also include dependency files

0c77e08

yiyuan-he mentioned this pull request Oct 30, 2025

feat(cloudwatch-applicationsignals-mcp-server): mcp eval framework #1618

Merged

6 tasks

mxiamxia reviewed Nov 3, 2025

View reviewed changes

...loudwatch-appsignals-mcp-server/awslabs/cloudwatch_appsignals_mcp_server/enablement_tools.py Outdated Show resolved Hide resolved

yiyuan-he added 7 commits November 3, 2025 11:42

add use this tool when guidance to enablement tool description

bee11f6

apply suggested changes

0855eaf

replace temp_directories fixture with module-level constant

3cf0aa3

rename platform to service_platform for consistency

ebf1dab

shorten enablement tool name back to get_enablement_guide

422e62e

revert enums back to strings to surface friendly error message

39bdc19

add additional tets for code coverage

8f57ebd

yiyuan-he force-pushed the get-enablement-guide-tool-setup branch from 7d34b32 to 8f57ebd Compare November 4, 2025 16:17

yiyuan-he added 3 commits November 4, 2025 10:26

add guidance for AI agents to resolve paths before calling tool in de…

89a246b

…scription

add explicit checklist workflow instructions in enablement tool descr…

50d4c42

…iption

remove generic verify step from tool instructions

65f78bb

wangzlei reviewed Nov 4, 2025

View reviewed changes

thpierce approved these changes Nov 5, 2025

View reviewed changes

mxiamxia approved these changes Nov 5, 2025

View reviewed changes

Merge branch 'main' into get-enablement-guide-tool-setup

8775921

yiyuan-he removed hold-merging Signals to hold the PR from merging waiting-for-codeowners Code owners are needed to review labels Nov 6, 2025

Merge branch 'main' into get-enablement-guide-tool-setup

0c061ea

Merge branch 'main' into get-enablement-guide-tool-setup

5c53987

yiyuan-he added this pull request to the merge queue Nov 6, 2025

Merged via the queue into awslabs:main with commit c64076b Nov 6, 2025
135 checks passed

yiyuan-he deleted the get-enablement-guide-tool-setup branch November 6, 2025 21:49

github-project-automation bot moved this from To triage to Done in awslabs/mcp Project Nov 6, 2025

yiyuan-he mentioned this pull request Nov 8, 2025

feat(cloudwatch-applicationsignals-mcp-server): add get_enablement_guide tool #1691

Merged

6 tasks

feat(cloudwatch-appsignals-mcp-server): Add get_enablement_guide MCP tool #1585

feat(cloudwatch-appsignals-mcp-server): Add get_enablement_guide MCP tool #1585

Uh oh!

Conversation

yiyuan-he commented Oct 24, 2025

Summary

Changes

User experience

Checklist

Acknowledgment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

codecov bot commented Oct 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

thpierce left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

wangzlei left a comment

Choose a reason for hiding this comment

Uh oh!

yiyuan-he commented Nov 5, 2025

Uh oh!

yiyuan-he commented Nov 6, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

codecov bot commented Oct 24, 2025 •

edited

Loading